<!--
     The contents of this file are subject to the Mozilla Public
     License Version 1.1 (the "License"); you may not use this file
     except in compliance with the License. You may obtain a copy of
     the License at http://www.mozilla.org/MPL/
    
     Software distributed under the License is distributed on an "AS
     IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
     implied. See the License for the specific language governing
     rights and limitations under the License.
    
     The Original Code is the Issuezilla Issue Tracking System.
    
     The Initial Developer of the Original Code is Netscape Communications
     Corporation. Portions created by Netscape are
     Copyright (C) 1998 Netscape Communications Corporation. All
     Rights Reserved.
    
     Contributor(s): 

     Contributor(s): Terry Weissman <terry at mozilla.org>
-->
<TABLE BORDER="0" CELLSPACING="1" CELLPADDING="3" BORDER="0" WIDTH="100%">
  <TR>
    <TD class="Header" nowrap>Querying and tracking issues</TD>  </TR>
</TABLE>
<TABLE BORDER="0" CELLSPACING="2" CELLPADDING="2" BORDER="0" width="100%">
  <TR>
    <TD VALIGN="top"><SPAN class="InputHeader">First, a clue about querying ...</SPAN>
  </TR>
  <TR>
    <TD class="PlainText" VALIGN="top"> 

    <P>The IssueZilla query form will allow you to call up a subset of
    the issue list. The way querying works, if you have nothing
    checked in a box, then all values for that field are legal. For
    example if you checked nothing in any of the boxes, you would get
    the entire issue list.

     <P>You can save the URL of your results list to your bookmark
     file in order to preserve queries. You can also save your query
     configuration to reuse later.

     <P><SPAN class="InputHeader">Now, the details ...</SPAN>
     <P>
     <A HREF="#queryfields">Issue query fields</A><BR>
     <A HREF="#queryresults">Sorting/customizing query results</A><BR>
     <A HREF="#customqueries">Customizing/remembering queries</A><BR>
     <A HREF="#trackissue">Tracking your issues or by assignee</A><BR>
     <A HREF="#otherqueries">Running other queries</A><BR>
     <A HREF="#browserinfo">Browser information</A><p>
     <A NAME="queryfields"><SPAN class="InputHeader">Issue query selection fields</SPAN></A>
     <P>
     <UL>
      <LI><SPAN class="InputHeader">Type</span> refers to the
      classification of issues as either <A
      HREF="/docs/DomainDocsIssues_EnterModify.html#issue_type">tasks,
      defects, features, or enhancements</A>.
      <P>
      <LI><SPAN class="InputHeader">Component</span> is the the part
      of the software in development associated with the issue if you
      are querying to find. If you don't choose a component or
      subcomponent, the query addresses all issues for the
      <I>project</I>.
      <P>
      <LI><SPAN class="InputHeader">Sub Component</span> is a subset
      of the component you selected in the previous field. If you
      don't choose a sub component, the query addresses all issues for
      the <I>component</I>.
      <P>
      <LI><SPAN class="InputHeader">Status</span> is set with <A
      HREF="/project/gridengine/docs/issue_lifecycle.html">NEW, ASSIGNED and REOPENED</A>
      selected as the default. When searching for issues that are
      UNCONFIRMED, RESOLVED, VERIFIED, or CLOSED, remember to change
      this status field appropriately.
      <P>
      <LI><SPAN class="InputHeader">Resolution</span> is the
      qualification of issues with a status of <A
      HREF="/project/gridengine/docs/issue_lifecycle.html#resolvedissues">RESOLVED,
      VERIFIED, OR CLOSED</A>. All resolved issues must be assigned
      one of these <A
      HREF="/project/gridengine/docs/issue_lifecycle.html#resolvedissues">values</A>.
      <P>
      <LI><SPAN class="InputHeader">Priority</span> queries for issues
      by their rank of importance using the following scale: P1 is
      highest priority, given to issues that should be addressed as
      soon as possible; P5 is the lowest priority.
      <P>
      <LI><SPAN class="InputHeader">Platform</span> is the type of
      computer the issues is associated with. This field is most
      critical when searching for defects. When querying for other
      types of issues, it may not be necessary to make a selection in
      this field.
      <P>
      <LI><SPAN class="InputHeader">OS</span> is the type of operating
      system the issue is associated with. Again, when querying for
      other types of issues, it may not be necessary to make a
      selection in this field.
      <P>
      <LI><SPAN class="InputHeader">Version</span> The release of the
      software associated with this issue. Leaving this field
      unselected queries all versions of the selected project or
      component.
      <P>
      <LI><SPAN class="InputHeader">Target Milestone</span> queries
      for issues associated with different project milestones, if your
      project has these. Milestones typically are dates when certain
      features or overall versions are expected to be completed.
      <P>
      <LI><SPAN class="InputHeader">Email</span> lets you query for
      issues by the email address of assignee, reporter, QA contact,
      cc list, or added comments. A duplicate field lets you further
      refine queries based on this criteria. To search for issues
      associated with an email address:
     <UL>
       <LI>Type a portion of an email address into the text field. 
       <LI>Select fields to query for association with that email address. 
     </UL>
     <P>The second field enables you to look for two different email
     addresses. If you specify both, then only issues matching both
     are returned in your query results. For example, this is useful
     to find issues "created by Ralph" and "assigned to Fred."  

     <P>You can also use the drop down menus to specify whether you
     want to match addresses by doing a substring match, regular
     expressions, or exact match of a fully specified email address.
     <P>
     <UL>
      <LI>Additional input fields let you further qualify queries by issue number(s), date changes, number of votes, and
changes in field values.
      <P>
      <LI>Summary is the one-line abbreviated description of the issue used by default in reports and query results. 
      <P>
      <LI>A description entry enables querying by text string from the longer, detailed issue description.
      <P>
      <LI>URL lets you query by the web page location associated with issues, when applicable.
      <P>
      <LI>Status Whiteboard is a field defined by the project owner
      (or users with administrative permissions in IssueZilla).  Input
      values to query by this field thus depend upon how it is being
      used in a particular project.  

      <P>Those who prefer to devise their own query schemes beyond the
      fields provided can <A HREF="/project/gridengine/docs/booleanchart.html">set up
      Boolean chart queries</A>.
     </UL>
     </UL>


     <P>
     <A NAME="queryresults"><SPAN class="InputHeader">Sorting and customizing query results</SPAN></A>

     <P>Before submitting a query, you can select to sort by issue
     number, importance, or assignee. After you submitted a query
     during a IssueZilla login session, you have the option to "Reuse
     the same sort as last time."

     <P>Once you view the query results, clicking on any of the column
     headings will sort the displayed results within that column.<P>

     <P>Using the links at the bottom of the query results page, you
     can also:
     <P>
     <UL>

      <LI>Switch to "long format" view of results to display complete contents of issues.

      <LI>Load a new query form.

      <LI>Enter a new issue.

      <LI>Change which columns appear in query results.

      <LI>Change several issues at once. (This option displays a page
      that lets you select issues from your query results list and
      modify specific fields in all of these simultaneously.)

      <LI>Send email to owners of issues listed.

      <LI>Edit the configuration of the last query.

     </UL>
     <P>
To add the target milestone for each issue to your query results -- and you should do so when a particular issue is slated
for release --
     <P>
      <OL>
       <LI>Do a query (or click "view assigned issues").
       <LI>Click the "change columns" link at the bottom. 
       <LI>Click the "target milestone" check box.
       <LI>Submit.  
      </OL>

     <P>The target milestone column will now included for all your subsequent queries because login sessions are
cookie-based. You can unmark this checkbox or mark others at any time to change your customized query results.

     <P>
     <A NAME="customqueries"><SPAN class="InputHeader">Remembered queries</SPAN></A>

     <P>Once you've set up a fairly complex query to ferret out
     certain issues, you can tell IssueZilla to "remember" your custom
     queries as a time saver. Using the options just above the
     <I>Submit query</I> button, you can save your most recent query
     under a unique name and reuse it anytime you are logged in to
     IssueZilla. You can also change and reset the default query that
     the query page loads during your login sessions.

     <P>To include your custom, named queries in the footer of the
     query page, use the "Edit prefs" link in the IssueZilla tool bar,
     and select the "Page Footer" option.  All of your named queries
     have the option to be included in the IssueZilla tool bar on
     every page or only on the query page.

     <P><A NAME="trackissue"><SPAN class="InputHeader">Tracking issues by assignee</SPAN></A>

     <P><B>To view a list of issues specifically assigned to you</B>, click the "My issues" link in the IssueZilla tool
bar.


     <P><B>To view other project members' assigned issues</B>, create
     a query using the "search the issue database" link and search by
     the "assigned to" field with the person's name entered. (The
     default setting for the "status" in the query screen includes
     NEW, ASSIGNED, and REOPENED.)


     <P>You can also generate reports by user and create a page of
     project members listed by name, each with a link to their
     specific list of issues.
     <P>
     <P>
     <A NAME="otherqueries"><SPAN class="InputHeader">Running queries not supported by the pretty boxes</SPAN></A>

      <P>There is a hacky way to do some searches that aren't
      supported by the query form.  The issue list script will build
      queries based on the URL, so you can add other criteria.

     <P>For example, if you wanted to see all issues reported against
     the X platform and assigned to jwz, you could ask for all issues
     assign to jwz, then edit the URL in the "Location" box, adding
     the clause "&rep_platform=X-Windows" to the URL.

     <P>Here is a list of some of the field names you could use for
     additional unsupported searches ...
     <P>
     version<BR>
     rep_platform<BR>
     op_sys<BR>
     reporter area<BR>
     issue_file_loc<BR>
     short_desc<BR>
     <P>
     <A NAME="browserinfo"><SPAN class="InputHeader">Browser notes</SPAN></A>

     <P>IssueZilla uses several non-standard Netscape extensions, but
     this does not seem to case any problem with other browsers.  The
     Lynx browser does work, but Lynx seems to cache results of a
     .cgi.  You'll sometimes need to press CONTROL-R to reload the
     screen to see an update.
    </TD>
  </TR>
</TABLE>

